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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 


PREFACE 


This document summarizes conventions and guidelines which are 
appropriate for APL Application Workspaces. APL Application 
Workspaces are debugged APL programs (sets of defined functions) 
which are regularly executed to produce results needed for 
support of development, manufacturing, and business operations. 


These conventions represent generally accepted, good practices 
for preparation of APL programs. However, they cannot all be 
rigidly required for every APL Application Workspace. Exceptions 
to these conventions may be appropriate depending on the user and 
application environments. Nevertheless, this document should be 
reviewed for all applicable conventions, and any exceptions 
should be made on the basis of recognized need. While there are 
alternatives to some of these conventions, these specific 
conventions are offered as a useful set to those programmers and 
installations who have not yet adopted their own. 


The use of these conventions will promote a common style in 
APL program code. This will contribute to ease of understanding 
and allow easier transfer of maintenance responsibility. These 
conventions also form a basis for guiding new APL programmers 
into good programming habits. 


The section on "Local System Conventions" should be replaced 
with special considerations and requirements relevant to the 
particular installation and the APL system in use. 


These conventions were compiled from a number of reports 
and papers and the contributions of reviewers. Special thanks 
are due S. Eusebi, J. Ever, C. Fair, L. Lewis, B. Martin, 

Y. Morita, P. Nicholson, R. Polivka, J. West, and C. Wilkes 
for material and comments. 
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I. DOCUMENTATION 


A. WORKSPACE DOCUMENTATION 


1. 


2. 


9. 


Workspaces must contain a DESCRIBE variable or function 
which provides documentation about the workspace. 


The DESCRIBE may refer to hardcopy documentation if it 
exists. In this case, DESCRIBE may contain just a brief 
summary of the nature of the application. 


If the DESCRIBE is the main documentation, it must give 
sufficient information to understand how to use the 
workspace. All user-invoked functions must be itemized 
with explanations. 


If the DESCRIBE is very large, it may be kept ina 
separate workspace. In this case, the DESCRIBE in the 
production workspace should simply point to the separate 
workspace. 


If a workspace consists of independent functions, 
documentation for each function may be included in a 
separate function or variable named with the suffix 
---HOW appended to the function name. 


Auxiliary workspaces may contain a DESCRIBE which refers 
to the main workspace. 


Latent expressions (OLX) should not invoke a lengthy 
DESCRIBE. If it is important, they should merely direct 
the user to the main documentation. 


Related workspaces should be named using the same prefix 
name, e.g., PLOT and PLOTUNLK (not UNLKPLOT). This will 
allow their names to appear together in a )LIB listing. 


A variable named CONTROL must contain the following 
information (alternative name: AUTHOR): 


Author/maintainer, phone, dept/bldg, loc 


10. A variable named WSID must contain the library number 


and name of the workspace and the date last updated. 
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I. DOCUMENTATION (CONTD) 


B. PROGRAM DOCUMENTATION 


1. Every function of an application must have a commented 
version stored on the system, which is maintained as 
the source copy. Comments may be deleted and/or the 
function locked to produce 4 separate execution-copy 
of the application. 


2. Every function must contain the following comments as 
its first lines: 


Line 1: Concise explanation of what the function 
does. This line should start with aa. 


Line 2: Level-number, date of last revision, 
programmer name. 


Subsequent lines: Descriptions of 
(1) Arguments. 
(2) Explicit result. 
(3) What functions are called. 
(4) What variables global to this function 
are used, changed, or created. 
(5) What files are processed. 
If necessary, this can refer to separate 
documentation in an "application notebook". 


3. Comments must be included in all functions to explain, 
as necessary, the steps in the processing and WHY they 
are done. Special notes should be included about 
unusual conditions, dependencies, or side effects. 


4. Comments must be on separate lines, starting with a, 
preceding the statements which they explain. This is 
to allow easy deletion for an execution copy, Le 
necessary. There should be an minimum average of 
1 comment line per 3 lines of code (25 percent comments). 


5. Comments must be kept up-to-date and accurate. 
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I. DOCUMENTATION (CONTD) 
C. APPLICATION MAINTENANCE DOCUMENTATION 


The following documentation must be produced and maintained 
in a note binder for each application workspace. These items 
should be produced using automated utility programs where 
available. 


1. Listings of the commented version of every function. 


2. Listings of the characteristics and values of all global 
variables stored in the workspace or on a file. 


3. A description of the structure and record formats of 
all files accessed or created on secondary storage, the 
auxiliary processors required, and any APL system 
environment dependencies. 


4. A summary of the environment of each workspace, displayed 
using the system commands: 


)LOAD wsname (to show name, date-saved, and 
OLX messages) 
)FNS 
)VARS (should have erased temp vars, init globals) 
)GRPS 
)GRP grpname (for each group) 
)SYMBOLS (should have been cleaned up via a )COPY) 
OWA 
OPw 
gro 
OLX 
)SI (should be empty) 
Other system variables, if not the same as ina 
CLEAR WS. 


5. An alphabetized summary listing of all functions and what 
they do. 


6. An indented listing of the function-calling structure, 
starting with each user-invoked function. 


7. Summary tables of global variables (used in what 
functions), function calls (from what functions), and 
workspace statistics (number of: functions, names, lines 
of code). 
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II. HUMAN FACTORS 


The level of user ability and experience with computers must 
be considered when designing an APL application. The 
following are considerations regarding understandability and 
user convenience. 


1. User-invoked functions should have short names (not more 
than 8 chars) that are meaningful and mnemonic. They 
should be niladic (no arguments). User inputs should be 
requested via prompting messages. This reduces the need 
to remember the syntax of commands. 


2. All prompting for user inputs should be done near the 
beginning of execution, if possible, especially when 
there is lengthy program execution. Prompting should be 
combined into one function in the program. This 
will allow the processing code to be used independently 
of any prompting. 


3. Lengthy processing should be split up into steps or phases. 
Do not make the user repeat any more than necessary to 
re-do or change the results. Display "progress messages" 
or transaction/record counts at key points in program 
execution to indicate the phase of processing which has 
been reached. This will indicate to the user that 
execution is continuing or has completed. 


4, Prompting messages should be clear to the user, but short. 
Long explanatory messages should be suppressible or have 
an alternate short form for experienced users. Messages 
should not wrap-around on the terminal screen. A width of 
64 characters fits on the 51xx series, 76-80 on the 327x. 


5. Extensive message text or menus should fill the terminal 
screen width, occupying as few lines vertically as 
possible. The complete text should fit on the screen 
at one time. If necessary, the terminal screen should 
be cleared first, under program or user control. 


6. Input requests should indicate the type of response 
expected, e.g., "(¥/N)". They should request brief user 
responses, e.g., the numbers of options which have been 
displayed in a list. The amount of user typing and 
spelling should be minimized. 


7. Keyboard input should consist only of lowercase characters 
(no underscores), numbers, blanks, periods, commas, and 
slashes, if possible. These keys are in the same positions 
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II. HUMAN FACTORS (CONTD) 


on most terminal keyboards. Use blanks as delimiters in 
preference to commas. 


8. All user input should be requested through ™, not 0, to 
allow program control over error checking and user inputs. 


9. The empty response should be allowed, to signal use of a 
default value or termination of execution. Defaults should 
be indicated in the prompting message. 


10. All program dialogue with the user should be worded in 
impersonal terms. All appearances of "humanness", such 
as evoked by "I" or "YOU", should be avoided. The 
computer is a machine. No other impression should be 
given. 


11. In user-prompting messages, refer to the "end-of-input" 
key as "RETURN" (the common typewriter label), e.g., 
ADJUST PAPER ... AND PRESS “RETURN”. If the application 
will be used on only one terminal type, the appropriate 
key label may be substituted (327x=ENTER; 51xx=EXECUTE) . 


12. Error messages should start with ** to distinguish them 
from prompting messages. 


13. Lengthy user input which will be needed during a repeat- 
execution of a command should be saved for re-use. 
This will reduce both the user errors in re-entry and 
the time needed for repeated executions. 


14, User-invoked functions should detect the presence of 
suspended functions in the workspace and terminate 
execution, e.g., via: 


+(1=p0LC)/s1 
>0,p0+'**xSUSPENDED FNS IN WS* 
S1: .... 


This will avoid problems with shadowed names and reduced 
workspace size. 
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III. CODING CONVENTIONS AND GUIDELINES 


A. CODE EFFICIENCY 


Code efficiency is important, since APL programs execute 
with interpreter overhead. However, it is of lower 
priority than reliable, correct execution and maintainable, 
adaptable program code. 


1. Programs should be coded for maximum APL execution 
efficiency. Vector and array operations should be 
used in preference to looping, whenever possible. 
Consult the APL PROGRAMMING GUIDE: VECTOR OPERATIONS, 
G320-6103, for examples of efficient APL statements 
for common operations. 


2. Limit the use of the execute (2) function to necessary 
situations, e.g. converting to numbers, because it 
has additional execution overhead compared to normal 
statements. When using execute (¢) with constructed 
APL statements, include comments showing the intended 
APL-prototype-code and describing any side effects, 
tc give a clear understanding of the intended result. 


3. Avoid combining statements artificially if execution 
speed is to be maximized, especially within loops. 


4. Pay special attention to the efficiency of code 
in heavily executed loops. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 
B. NAMES 


1. User-invoked functions should have short names (not more 
than 8 chars) that are meaningful, mnemonic, and easily 
spelled, with no underscores. 


2. Names of subfunctions and variables should be short and 
mnemonic, for ease in reading the code. A vector can 
be named V, a matrix M, an array A, a boolean or 
logical variable B or LZ, and an explicit result Z. 


3. Naming Convention, to distinguish among subfunctions 
and local, semi-global, and global variables: 


Subfunctions - last one or two characters 
underscored: SUBE. 

Local Variables and Labels - no underscores. 

Semi-Global Variables - first one or two characters 
underscored: SEMI. These are variables 
localized only in the highest, user-invoked 
functions, which are used for communication 
among subfunctions. 

Global Variables - all characters underscored: 
GLOBAL. These are variables which remain 
in the workspace after function execution 
has completed. 

Groups - suffix ---GP on a descriptive name, such 
as the main user-invoked function: REPORTGP. 
No underscores. 


4. Global variable names should have 4 or more characters. 
This will reduce the possibility of conflict with short 
local names within functions. 


5. Global variables should be generated and initialized 
by functions. Alternatively, include an "initialization 
function" which creates all global variables with their 
initial values and documents their purpose and 
characteristics. This will allow recovery if a global 
constant or variable is accidentally destroyed. 


6. All temporary variables should be localized within a 
function. The list of local variables should be in 
alphabetical order. 


PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 


III. CODING CONVENTIONS AND GUIDELINES (CONTD) 


B. NAMES (CONTD) 


7. Local variable names of 1 or 2 characters should 
be re-used among all functions, to reduce symbol 
table requirements. Unique names should be avoided. 
However, mnemonic value of names should be maintained, 
if possible. Short local variable names will keep the 
header statement short and will assist in the 
recognition of idioms. 


8. Large temporary variables should be assigned an empty 
value (V+10, V+'', V+0p...) to recover storage after 
use. NOTE: (OFX can be used, but it eliminates 
debugging evidence that a variable has existed. 


9. Use a localized temporary variable to capture unwanted 
temporary results, e.g., Q«UFX .... Do not use 
system variables (OAI+D£X ...). This confuses the 
proper use of these variables. 


10. Statement labels should be short (up to 3 characters). 
Use comment statements to explain the processing. 


11. Use a common set of labels in all functions, to reduce 
symbol table requirements. Avoid unique labels. 


12. Labelling Convention, to distinguish internal function 
structure: 


S-- = S + numeric suffix, for downward-branch labels, 

unless also a loop label: S51. 

LP- = LP + numeric suffix, for upward, looping 
branch labels: JLP1i. 

ER + numeric suffix, for downward-only branch 
labels on error processing: FR1. NOTE: 
This is only for multiple branches to the 
same error processing. Error processing 
should immediately follow the code which 
detects the error. It should not be 
located anywhere else. 


ER- 


Each label-type has a separate numeric sequence, in 
increasing order. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 


C. BRANCHING AND LOOPING 


1. 


7. 


For execution efficiency and function clarity, branching 
and looping should be used only when APL array 
operations are not possible or practical. 


All branches must be to labeled lines or to 0. Do 
not use relative branching (+0ZC+2), computed 
labels (+S5+K>0), or statement numbers. (See the 
label-naming convention under "NAMES".) 


Use only branch-statement types that execute the same 
in either indexing origin. Acceptable branch 
statements usable for single and multi-way branches 
are: 


>( CONDITION) /LABEL 
>((COND1),(COND2),...)/S51,82,... 


Branching subfunctions (e.g. IF) should be used only for 
documentation purposes, since they usually increase 
execution time. They should be removed prior to 
execution. 


Branch statements that exit the function should show 
an explicit 0. 


Leading-decision loops should be used in preference 
to other types. Such loops consist of loop 
initialization, test for exit condition, loop 
processing, and unconditional branch back to the test, 
in that order: 


I+0 
[P1:+(LIM<I+I+1)/S1 
«+. (PROCESSING) 
>LP1 
Si:... 


Execution should flow downward through a function. 
Upward branches should occur only at the end of loops. 
All other branches should be directed downward in 
the function. This will help to produce an internal 
modular structure like IF-THEN-ELSE and DO-WHILE 
structures. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 


C. BRANCHING AND LOOPING (CONTD) 


8. 


10. 


Suspend function execution when abnormal conditions 

are detected, so that the error environment can be saved 
for debugging. An error message describing the abnormal 
condition should be displayed prior to termination. Use 
niladic branching (+) only where necessary, e.g., when 

a security check indicates unauthorized access. 


Unconditional branches may be combined with preceding 
assignment statements using a line-separator function or 
the form +LP2,9V+.... This is useful for reducing 
program listing length and OCF size. 


Executed (#) branches should not be used, because 
execution efficiency is important. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 


D. DEFINED FUNCTION AND SUBFUNCTION STRUCTURE 


1. 


Function statements should not exceed the size of the 
terminal line. Preferably, function listings should 
fit on 8.5x11-inch paper without wrap-around, i.e., 
up to 65 characters per line. Exception: Header 
statements with many local variables. 


Function statements should be combined only in 
meaningful and execution-efficient ways. Temporary 
storage requirements should not become excessive as 
a consequence of long statements. 


Use parentheses only when necessary. No occurrences of 
2 or more right parentheses are necessary. Rearrange 
the order of arguments to eliminate parentheses. Avoid 
cluttered statements with excessive or deep nests of 
parentheses or brackets. 


Define subfunctions for significant operations used in 
2 or more places or likely to be useful elsewhere. 
Use existing public library functions (e.g., PLOT 
functions) if they meet requirements. 


Function listings including comments should fit on one 
page. Limit functions to 40-50 statements if possible. 
It may be convenient to further limit functions to the 
size of the terminal display, if smaller. 


Use of global variables should be minimized. Whenever 
possible, data should be passed between functions as 
function arguments and explicit results. Alternatively, 
store globals in a file so that only 1 copy of them 
will have to be maintained for use by multiple 
workspaces. 


Return codes from subfunctions, if any, should be 0 
for normal completion and 1 (non-zero) for error returns. 


Input/Output to a terminal, printer, or other I/O 
device should be routed to a subfunction for that type 
of output. This will simplify changes if a different 
device must be substituted. 


Each top-level (user) function should have a common 
end point. This makes it easier to add extra 
processing code, such as calls to functions which log 
application usage. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 
D. PROGRAM AND SUBROUTINE STRUCTURE (CONTD) 


10. Prompting for user inputs should be combined into one 
function, if possible, to be handled all at one time. 


11. Functions should be locked only when necessary. 
Unlocked functions allow execution to be restarted 
if interrupted and allow error environments to be 
saved for debugging. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 


E. CODE AND SYSTEM DEPENDENCIES 


1. 


No obsolete APL functions should be used: 
no I-beams, no semi-colon (;) terminal output. 


Programs should not be written with system-dependent 
code, if possible. When necessary, isolate such code 
in subfunctions, so that it can be replaced easily. 


Avoid indexing special characters or terminal control 
characters from DAV. Include all printable characters 
as literals or variables. 


All non-default workspace parameters (e.g., O10, OPW) 
should be localized and set at the beginning of the 
affected functions. 


Data in reports should contain only characters that 
are printable as both APL and EBCDIC, so that they 
may be printed on either a terminal or a high-speed 
printer with a standard print train. 


Output formats should be device independent, if 
possible, within general class of device. 


Design programs for easy modification. Avoid multiple 
explicit references to constants or literals. 

Use variables to hold "constants" that might later 

be changed, e.g. page size. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 
F. OPTIONAL CONSIDERATIONS 


The following optional guidelines may be appropriate in 
certain situations. Some are applicable only to unlocked 
APL functions. 


14. Do not re-specify (destroy) function arguments within 
a function. This will make it possible to restart an 
interrupted function by branching to the first line, 
since all arguments will still be available for re-use. 
NOTE: To be able to restart, global variables also 
must not have been changed. 


2. Make function statements restartable. Make all 
assignment (+) operations which update a variable the 
primary (leftmost, last) operation in a statement. 
Usually this involves isolating on separate lines any 
operations which increment or change a variable which 
existed before the statement was executed. Then, when 
execution of the statement is interrupted, it can be 
restarted without having to reset any variables. 
NOTE: This does not apply to assignment operations 
which create new variables, since these will just be 
recreated when a statement is restarted. 


3. Write generalized subfunctions which can process 
arguments of variable rank and shape, and which will 
not fail if the argument is empty. 


4. Use each local variable for only one purpose within 
a function. This will reduce the risk of usage- 
conflict errors, especially in looping code. It will 
also make it possible to determine whether a variable 
has been used yet by checking its value. For large 
temporary variables it may be necessary to assign an 
empty value to recover storage after use. 


5. For functions whose main purpose is to create printed 
results at the terminal, write them so they yield the 
text to be printed as an explicit result. This will 
allow the display of the result to be interrupted 
without leaving a suspended function. It will also 
allow the results to be stored and saved for re-display 
without re-execution. A vector result with embedded 
“new-line" characters will print text having unequal 
length lines, avoiding the extra space that padding 
for a matrix. result would require. 
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III. CODING CONVENTIONS AND GUIDELINES (CONTD) 
F. OPTIONAL CONSIDERATIONS (CONTD) 


6. Store all message text, e.g., prompting and error 
messages, together in separate functions or variables. 
This will simplify the changes necessary to convert 
programs for use with a different language. Be 
careful to avoid any code dependency on the message 
length. 
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IV. RELIABILITY AND RECOVERY CONSIDERATIONS 


1. 


Applications should be programmed to work under all 
conditions and detect user input errors. User errors 
should not cause an APL execution error or abend. 


The results of I/O operations should always be checked. 
Appropriate error processing should be executed when 
error conditions are detected. 


Write an updated record back to its file as soon as the 
update is complete, if CPU time and cost are not critical. 


Use replacement updating rather than additive updating to 
avoid double-updating if the entire job is not completed 
and must be rerun. 


When processing large files, maintain a record on the file 
which contains the number of the last record/transaction 
processed, plus any other data needed for restarting 
execution if the job is interrupted. This can also 
include an indicator that processing has started. If it 
is found "on" when the file is opened, it indicates that 
processing was not complete and must be restarted. 


Provide the capability to restart execution, either as 
a user-invoked function RESTART or as a OLX-invoked 
automatic restart. 


To allow for automatic restart of execution, localize the 
latent expression OLX in the highest-level function and 
specify it as [LX+'+RESTART', Define the function 
VZ+RESTART ... which re-establishes the necessary 
processing environment, e.g., shared variables with the 
auxiliary processor, file positioning, etc., and if 
successful, returns 2+1401C. Then execution will restart 
whenever a saved, interrupted workspace is )LOADed. 

If unsuccessful, RESTART should display '**UNABLE TO 
RESTART' and suspend execution. 
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V. SECURITY CONSIDERATIONS 


The following list describes ways to make an APL application 
program secure. The level of security needed is in direct 
proportion to the confidentiality of the data. Items (1), (3), 
and (10) are very important pieces in any security scheme. 
Applying these techniques is the responsibility of the 
application developer and user. 


1. All critical functions should be locked. 


2. Critical functions should not call other functions which 
are unlocked, nor should they request data via Q-input. 


3. All critical workspaces should be locked or RACF-protected, 
where available. 


4, All sensitive data stored on files should be encoded and/or 
RACF-protected. 


5. Auxiliary processor linkage and access code should be 
included within locked functions. 


6. Encode/Decode functions should have their algorithms and/or 
"character string" keys changed periodically. 


7. Critical variables (especially shared variables) should be 
localized within locked functions. 


8. An additional password should be required before access is 
allowed to critical options within a workspace. 


9. Data set names should be hidden in locked functions, or 
generated by a function executed by a latent expression 
which also checks the users sign-on number for validity. 


10. Command data sets (TSIO only) should be used to control 
access to critical files which have been created as 
reserved data sets. 


11. Unauthorized attempts to access data sets should be 
captured on access logs and/or audit trails, so that any 
security violators are identified. 


12. An application security administrator should control or 
monitor items (6), (8), (10), and (11). 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 
VI. LOCAL APL SYSTEM ENVIRONMENT CONVENTIONS 


This section should be replaced with the conventions of the 
local APL system administration. These conventions may deal 
with such topics as: 


1. Name and number conventions for APL workspaces, 
libraries, and data sets. 


2. Logging of system usage by application. 


3. Labelling and handling of classified programs and 
output. 
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APPENDIX A: Summary Of APL Programming Conventions 


WORKSPACE DOCUMENTATION: 
DESCRIBE - explain use of all programs. 
---HOW - explain use of 1 program. 
CONTROL/AUTHOR - identify owner, address, phone. 


PROGRAM DOCUMENTATION: 
Comments on all functions; delete for execution. 
1st-line summary of function processing. 
Description of arguments, results, interfaces. 


HUMAN FACTORS: 
Command names up to 8 chars; no arguments. 
Long/short prompting; progress messages. 
Keep inputs short; show answers expected. 
Use [M-input; allow empty response. 


CODING CONVENTIONS: 

Use vector/matrix/array idioms. 

Names: SUBE; SEMI; GLOBAL; ---GP. 

Alphabetize local variables; use short names: JV,M,A,B,L,2 

Branching: +(CONDITION)/LABEL; downward flow. 

Labels: $1 (downward branch); JLP1 (upward); 
ER1 (error); 0 (exit). 

Leading-decision loops. 

40-50 lines/function; up to 65 chars/line. 

I/O through subfunctions. 

Avoid DAV dependency; localize O10, OPW. 


RELIABILITY: 
Detect user-input errors. 
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APPENDIX B: An Example Which Follows The Conventions 


This appendix contains part of the functions for an APL program. 
It is a comprehensive example which illustrates the application 
of many of the programming conventions described in this Guide. 
The section numbers of the specific conventions which this 
appendix illustrates are: 


I.A.5 
I.B.1; 2, 3, 4, 5 
I.C.1, 5, 


II.1, 2, 3, 4, 6, 8, 9, 10, 12, 14 


III.A.1, 2, 3, 4 

III.B.1, 2, 3, 6, 7, 8, 10, 11, 12 
III.C.1, 2, 3, 5, 6, 7, 9 

III.D.1, 2, 3, 4, 5, 6, 7, 10, 11 
III.E.1, 3, 4, 7 


This example shows how a program can be meaningfully split into 
several functions. It makes use of a couple of generalized 
subfunctions which could be obtained from a library of standardized 
subfunctions. It is also an example of how APL processing can be 
composed from many basic APL idioms such as found in 
APL PROGRAMMING GUIDE: VECTOR OPERATIONS, G320-6103. 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 
APPENDIX B: An Example Which Follows The Conventions (contd) 


RELABELHOW 

“RELABEL” RELABELS APL DEFINED FUNCTIONS WITH A COMMON SET OF 
LABEL NAMES. THIS WILL REDUCE THE NUMBER OF NAMES THE SYMBOL 
TABLE MUST HOLD WHEN THESE FUNCTIONS ARE IN A WORKSPACE. 


FUNCTIONS ARE RELABELLED ACCORDING TO THE FOLLOWING CONVENTION, 
WHICH HELPS TO DISTINGUISH INTERNAL FUNCTION STRUCTURE: 


IP + NUMERIC SUFFIX + REPLACES ALL LABELS WHEN THE LABEL IS 
ALSO FOUND ON THE SAME LINE OR A SUBSEQUENT LINE, I.E. 
UPWARD BRANCHES. 

S + NUMERIC SUFFIX + REPLACES ALL LABELS WHICH ARE THE LAST 
OCCURRENCE OF THAT NAME IN THE FUNCTION. 


LABELS UP TO 4 CHARACTERS (LP99, S999) CAN BE GENERATED. 


LABELS BEGINNING WITH “ER” ARE ASSUMED TO BE LABELS ON “ERROR” 
PROCESSING AND ARE NOT CHANGED. LABELS WHICH ARE NOT REFERENCED 
ARE DELETED. 


RELABELLING IS CANCELLED IF: 


(1) DUPLICATE LABELS ARE FOUND. 

(2) A NEW LABEL IS FOUND TO ALREADY OCCUR IN THE FUNCTION. 
THIS CAN BE CAUSED BY A BRANCH STATEMENT TO A MISSING 
LABEL. 


IF THE RELABELLED FUNCTION DEFINITION CANNOT BE FIXED (OFX 
FAILS), THE FUNCTION MATRIX WILL BE STORED UNDER THE NAME 
“BADFCN” WITH A NUMERIC SUFFIX, E.G., “BADFCNS5”. AFTER THE 
PROBLEM LINES ARE CORRECTED, THE FUNCTION CAN BE FIXED BY 
“OFX BADFCNS”. OFX FAILURES WILL OCCUR IF THE RELABELLED 
FUNCTION IS PENDANT OR SUSPENDED IN THE WORKSPACE. 


TO USE “RELABEL”, ENTER: )PCOPY 12 UTILS RELABELGP 


“RELABEL” PROMPTS THE USER FOR A FUNCTION NAME OR THE NAME OF 


A MATRIX OF FUNCTION NAMES. IF AN “*” IS TYPED, THE USER WILL 
BE PROMPTED TO ENTER A LIST OF NAMES. IF A “3” IS ENTERED 
INSTEAD, ALL FUNCTIONS IN THE WORKSPACE WILL BE RELABELLED. 


FUNCTION NAMES ARE DISPLAYED AS THEY ARE PROCESSED. 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 
APPENDIX B: An Example Which Follows The Conventions (contd) 


RELABEL 

WAME, LISTNAME, 2,3 (2=VARS, 3=FCWS] 
OR * C=ENTER LIST] :TESTFW1 

TESTFN1 

ERROR” LABELS UNCHANGED: ER1 ER2 
**LABEL “S12” NOT REFERENCED; DELETED. 


RELABEL 
NAME, LISTNAME, 2,3 [2=VARS, 3=FCNS] 
OR * (=ENTER LIST] :* 
ENTER NAMES, 1 AT A TIME 
DUMMY 
TESTFN2 


SORT LIST? (Y/N) :W 

DUMMY 

**NOT AN UNLOCKED FCN 

TESTFN2 

**NEW LABEL “S1" ALREADY OCCURS, LINES: 4 11 


)GRP RELABELGP 
REQNAM REPVS RELREP RELMAT FIWRD RELABEL 


1. RELABEL 

. 2. REQNAM 

. 2. RELMAL 

. 3. RELREP 

. oo... 4. PIWRD 

. . « 4. REPVS 
PCN _SYNTAX USE 
I+V FIWRD S FINDS STARTING INDICES I OF WORD S IN VECTOR V 
RELABEL RE-LABELS FCN TO $1,S2,.,LP1,LP2,.(LEAVES ER..) 
RELMAL LB PROCESSES FUNCTION MATRIX; CALLED BY “RELABEL™ 


Z+RELREP LB REPLACES LABELS; CALLED BY ~RELMAZ™ 
Z+NS REPVS LI REPLACES OLD STRG (p0S),I WITH NEW STRG NS IN VEC Y¥ 
MZZ+*REQNAM PROMPTS USER FOR LIST OF NAMES 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 


APPENDIX B: An Example Which Follows The Conventions (contd) 


V RELABEL;B;C;F;L;LB;W;ALF;2;M;010 
[1] aamRE-LABELS FCN TO S1,S2,.,LP1,LP2,.( LEAVES ER..) 
[2] a- 2/26/81 16.12.10 TPHO44 
{3] aLIMITS: 4-CHAR LABELS ($999,LP99) 
[4] aCALLS: RELMAZ, REQNAM 
{[5] aUSES (SEMI)GLOBALS: ALF, I, M 
[6] 2(1#p0LC)/'''**SUSPENDED FNS IN WS'*',pQIO+1 
[7] aOBTAIN FCN NAMES 
C8] +( 0¢p F+REQNAM)/0 
[9] DELETE THESE 6 UTIL FCNS FROM LIST 
[10] B+ 6 7 p'RELMAZ RELREP REPVS FIWRD REQNAM RELABEL' 
C11] B+(6,C+(14pF)f14+pB) +B 
C12] FeCa/(((C1tpF),C)+F)V.2QB)¢F 
(13] aPROCESS ALL NAMES IN LIST 
C14] +(0=C+1tpF)/[+0 
{15] aSPECIFY LABEL-CHARS; PUT LIKELY LABEL-CHARS AT HEAD 
[16] aOF LIST, TO REDUCE SEARCH (e) TIME 
(17] ALF«'SLPER12345678900ABCDFGHIJKMNOQTUVWXYZ' 
{18] ALF+ALF, ' SABCDEFGHIJKLMNOPQRSTUVWXYZ' 
C19] LP1:+(C<[+[+1)/0 
[20] aDISPLAY NAME; CHECK WHETHER OCR OBTAINED 
21] +(~OepM+OCR O+FLZ;1)/s1 
C22] +LP1,p0+'**NOT AN UNLOCKED FCW! 
[23] aOBTAIN WIDTHS UP TO COLONS (WIDTHS OF LABELS) 
C24) S1:+( 0=pW+( BeW<1t+pM) /W++/a\Me":")/LP1 
(25] aOBTAIN LINES HAVING COLONS, TO RIGHTMOST COLON 
C26) LB+ylB/11teM3.L+l /W) 
27] aPAD SHORTER “LABELS” WITH BLANKS 
C28] LB+(pLB)pB\(B+,We.>(1L)-1)/,LB 
(29] aDELETE ROWS WITH NON-LABEL CHARS, THEN ANY 
(30] aALL-BLANK COLS, IN CASE “:” OCCURS OTHER THAN 
31] eAFTER A LABEL (E.G., DHIS FCN!) 
[32] LB+(v/LBe* ')/LB+(A/LBe' ',4LF)4¢LB 
(33] aQUIT IF DUPLICATE LABELS 
34 >(A/B+a/( Bo. <B+11tpLB)VLBV.#8LB)/S2 
C35] +LP1,p0+'**DUPLICATE LABELS: ',,((~B)#LB)," ' 
36] aADON'T CHANGE “ERROR” LABELS 
C37] S2:+(~v/B+(((14+pLB),2)+LB)A.='ER')/S3 
38] '“ERROR™ LABELS UNCHANGED: ',,(B/LB),' ' 
{39] aSKIP TO NEXT FCN IF NO LABELS LEFT 
C40] $3:>(0=1+pLB+(~B)/#LB)/LP1 
41] aREPLACE LABELS USING TEMP LABELS TO AVOID CLASHES 
42] RELMAZ LB 
C43] +LP1 

v 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 
APPENDIX B: An Example Which Follows The Conventions (contd) 


VY MZZ<REQNAM;1I2Z;L22;N2Z 
14] aaPROMPTS USER FOR LIST OF NAMES 
2] a- 2/26/81 16.12.10 TPHO4Y 
[3] aMZZ = MATRIX OF NAMES (EMPTY VECTOR IF NO USER INPUT) 
[4] aOBTAIN NAMES BEFORE ANY LOCAL VARS CREATED 
5] NZZ+ONL 2 3 
6] PROMPT FOR FCN/VAR NAME(S) 
C7) 'NAME, LISTNAME, 2,3 [2=VARS, 3=FCNS]' 
{8]  L22Z+pM+'oR * [=ENTER LIST] :* 
C9] +(0=0MZZ+LZ2Z+0)/0 
10] a"2,3 = USE ONL 2 AND/OR 3; “*” = PROMPT FOR LIST 
11] +('23%'=14MZZ)/S1,51,S52 
12] aFORCE MATRIX SHAPE ON INPUT NAME 
13] MZZ«(~2t 1 1 ,pMZZ)pMZZ 
44] aEXIT IF NOT A VARIABLE (JUST A “NAME”; NOT A “LISTNAME™) 
(15] +(2#0wc 222+Mzz(OI0;1)/0 
[16] aTEST FOR CHAR MATRIX (LIST OF NAMES) 
[17] alF NOT, EXIT (MUST BE SINGLE VAR-NAME) 
Cig] +((' '#0\0pIZZ)v2eppIZ2Z+ab2ZZ)/0 
[19] aSET CHAR MATRIX AS RESULT LIST 
[20] +S3,pMZ2«I2Z 
(21] aOBTAIN ALL FCNS AND/OR VAR NAMES IN WS 
[22] S4:MZ2+((ONC NZZ)e('23%e34MZZ)/ 2 3)4N2ZZ 
[23] aDELETE THIS FCN FROM THE LIST. TEST FOR ANY LEFT 
24] MZZ+(MZZv.#(~1toMZZ)+"REQNAM')4MZZ 
[25] +(0<1+pMZZ)/S3 
[26] +0,p0+'**NONE IN WS! 
[27] aBUILD LIST FROM USER INPUT 
[28] S2:MZZ+ 0 0 pO 
[29] ‘ENTER NAMES, 1 AT A TIME! 
[30] LP1:+(0=pL22+,0)/S3 
31] aAINCREASE WIDTH OF LIST OR NAME, AND CATENATE 
32] MZZ+((0 1 xpLZZ)[pMZZ)+MZz 
[33 +LP1,0MZZ+MZZ,COIO](1+0MZZ)+L22 
34] aSKIP SORT IF 1 NAME OR EMPTY 
35] S3:4(1214pMZZ)/0 
[36] L22+pM+'SoRT LIST? (Y/N) :' 
C37 >('Y¥'21422Z2+0)/0 
38] aASORT THE LIST ALPHAB 
39] 22+Or0+(pmMz2z)C1+0I0) 
Cuo] LP2:+((OL0-1)=1Z2+IZZ-1)/0 
44] +LP2,pMZ2«MZZCh(' ',04V)1MZ20 512213] 
v 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 


APPENDIX B: An Example Which Follows The Conventions (contd) 


V RELMAZ LB;B;D;I;L3N3C3V¥ 
{1] aaPROCESSES FUNCTION MATRIX; CALLED BY “RELABEL™ 
C2] a- 2/26/81 16.12.10 TPHO4Y 
C3] aLB = MATRIX OF OLD LABELS 
[4] CALLS: RELREP 
5] aUSES (SEMI)GLOBALS: C, I, My Y 
6] ARAVEL FCN WITH SEPARATORS 
C7] Y+,(C+''"pOAV) 
[8] PERFORM LABEL REPLACEMENT; EXIT IF NO CHANGE 
[9] +(O<RELREP LB)/M+0 
(10] aREBUILD OCR MATRIX, LINE-BY-LINE 
11] M+ 0 0 p¥+ity 
C12] LP1:+( 0=B+pV¥)/S1 
(13] aOMIT LINE IF ALL BLANKS OR EMPTY 
C14 Dea/* t=Le(I+(Yie)-1)4¥ 
C15] +(DvB=1+pY¥+(I+1)+¥)/LP1 
(16] aINCREASE MATRIX OR LINE, AND CATENATE 
17] M<((0 1 xpZL)FoM) ty 
C18] Mey, Cid(1+pM)tz 


C19 +LP1 
(20] aFIX FCN DEFN; CHECK WHETHER CONVERTED 
C21] S1:4(' "=0\0pN+OFX Y4)/0 


22] aIF OFX FAILS, STORE FCN-MATRIX IN “BADFCW-". 

23] aEXECUTE: BADFCNS+Y¥ 

24) e(B+'BADFCN',¥Z),'+M! 

[25] aUSER MUST CORRECT BAD ROWS; THEN: (OFX BADFCW- 

26] ‘'x«*OQFX FAILED ON ROW ',(¥N),'. FCN IS IN MATRIX “',B,' 
v 
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PROGRAMMING CONVENTIONS FOR APL APPLICATION WORKSPACES 


APPENDIX B: An Example Which Follows The Conventions (contd) 


Vv 2+RELREP LB;B;D3J3K3L3LC3;R353SL 

aaREPLACES LABELS; CALLED BY “RELMAT™ 

a- 2/26/81 16.12.10 TPH944 

aLB = MATRIX OF OLD LABELS 

aZ = 0 IF FCN-MATRIX CHANGED, NEEDS OFX; Z > 0 + NO CHANGE 
aCALLS: FIWRD, REPVS 

aUSES (SEMI)GLOBALS: (C, ¥ 

aINIT MATRIX-OF-NEW-LABELS SL, LINE-LABEL-CTR LC 
SL+(0,D+4)pLC+( 2+2)pJ+0 

ASUBSTITUTE TEMP LABELS “Q--~ FOR EXISTING LABELS. 

a’ D--" WILL BE VALID “NAMES” THAT WON'T CLASH WITH ANYTHING 
LP1:+((1t+pLB)<d+d+1)/S4 

aFIND STARTING INDICES OF OLD LABEL 

+(1<pkK+Y PIWRD L+(Le' ')/L+*LBLJ31)/S1 

aIF ONLY 1 OCCURRENCE, MUST BE UNUSED LABEL. 

ADELETE UNUSED LABEL AND COLON FROM FCN 

Y«'! REPV(1+pL).x 

'e*LABEL ',L,* NOT REFERENCED; DELETED.' 

aSET RETURN CODE FOR OFX 

+LP1,9Z+0 
aIS LAST OCCURRENCE THE LABEL (CHECK FOR COLON)? 
S1:Beit': "=V0(pY)L(~1tK)+eL) 

ACHECK FOR NO BRANCH IF LAST 2 OCCURRENCES IN SAME LINE 
a( LABEL REFERENCE WITHIN SAME LINE, IF NO “+”, = S--) 
+( Cv. =S+K0~1+pKI]+K[pKI+tY)/S2 

Beitt+ta.48 
aIF NOT, IS LOOP LABEL. INCREM COUNTER OF THAT TYPE AND 
ABUILD LOOP OR FORWARD BRANCH LABEL, AS APPROP 
$2:S+(2 “10B]+'LP S$"), ¥LCCBI+LC(BI+1 
aIF SAME AS OLD LABEL, SKIP TO NEXT LABEL 

+((pL)#pS)/S3 

+(LA.=S)/LP1 

aADD TO LIST OF NEW LABELS 
S3:SL+SL,(1] Dts 
AREPLACE OLD LABEL WITH TEMP LABEL 

+LP1,p¥+('O',S) REPVS(pL),xK 

aQUIT IF NO NEW LABELS 
S4:4+(0=R+14pSL)/J+0 
aREPLACE TEMP LABELS WITH NEW LABELS 
LP2:>(R<d+Jd+1)/Z+0 
ACHECK FOR OCCURRENCE OF NEW LABEL; QUIT IF EXISTS 
a(MAY HAVE BEEN A MISSING LABEL IN FCN) 

+(O0=pK+Y FIWRD S+(S#' ')/S+*SLUd3;1)/S5 
aCOMPUTE LINE NUMBERS WHERE FOUND; DISPLAY MSG; Z+NO OFX 
Z+p K+ 1++/Ke.>(V=C)/10V 

+0,p[+'**NEW LABEL “',S,*” ALREADY OCCURS, LINES: ',¥K 
aFIND STARTING INDICES OF TEMP LABEL 
SS5:+(0=pK+Y FIWRD L+(Le' ')/L+'O',SLCd;1)/LP2 
AREPLACE WITH NEW LABEL 

+LP2,0Y*+S REPVS(pL),K 

Vv 

26 


Staples can cause problems with automated mail sorting equipment. 


Note: 


Please use pressure sensitive or other gummed tape to seal this form. 


: ; READER'S 
APL Programming Guide COMMENT 


Programming Conventions FORM 
G320-6735-0 


You may use this form to communicate your comments about this publication, its organization, or 
subject matter, with the understanding that IBM may use or distribute whatever information you 
supply in any way it believes appropriate without incurring any obligation to you. 

Your comments will be sent to the author’s department for whatever review and action, if any, is 
deemed appropriate. Comments may be written in your own language; use of English is not required. 
Note: Copies of IBM publications are not stocked at the location to which this form is addressed. 
Please direct any requests for copies of publications, or for assistance in using your IBM system, to 
your IBM representative or to the IBM branch office serving your locality. 

Possible topics for comment are: 


Clarity Accuracy Completeness Organization Coding Retrieval Legibility 


If you wish a reply, give your name, company, mailing address, and date: 


What is your occupation? 


Number of latest Newsletter associated with this publication: 


Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. (Elsewhere, an IBM 
office or representative will be happy to forward your comments or you may mail directly to the address 
in the Edition Notice on the back of the title page.) 


G320-6735-0 


Reader’s Comment Form 


Fold and tape Please Do Not Staple 


BUSINESS REPLY MAIL 


FIRST CLASS PERMIT NO. 40 ARMONK, N.Y. 


POSTAGE WILL BE PAID BY ADDRESSEE: 


International Business Machines Corporation 
Department 824 

1133 Westchester Avenue 

White Plains, New York 10604 


Fold and tape Please Do Not Staple 


Fold and tape 


NO POSTAGE 
NECESSARY 
IF MAILED 


IN THE 
UNITED STATES 


Fold and tape 


aur Buoly plos 10 nQ-— — —— 


OSEL9-0ZED ‘“W'S'N U! palug suORUeAUOD BulWWesBOIg apIND Burwwesboig TdV 


Staples can cause problems with automated mail sorting equipment. 


Note: 


Please use pressure sensitive or other gummed tape to seal this form. 


: ; READER'S 
APL Programming Guide COMMENT 


Programming Conventions FORM 
G320-6735-0 


You may use this form to communicate your comments about this publication, its organization, or 
subject matter, with the understanding that IBM may use or distribute whatever information you 
supply in any way it believes appropriate without incurring any obligation to you. 

Your comments will be sent to the author’s department for whatever review and action, if any, is 
deemed appropriate. Comments may be written in your own language; use of English is not required. 
Note: Copies of IBM publications are not stocked at the location to which this form is addressed. 
Please direct any requests for copies of publications, or for assistance in using your IBM system, to 
your IBM representative or to the IBM branch office serving your locality. 

Possible topics for comment are: 


Clarity Accuracy Completeness Organization Coding Retrieval Legibility 


If you wish a reply, give your name, company, mailing address, and date: 


What is your occupation? 


Number of latest Newsletter associated with this publication: 


Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. (Elsewhere, an IBM 
office or representative will be happy to forward your comments or you may mail directly to the address 
in the Edition Notice on the back of the title page.) 


G320-6735-0 


Reader’s Comment Form 


Fold and tape Please Do Not Staple 


BUSINESS REPLY MAIL 


FIRST CLASS PERMIT NO. 40 ARMONK, N.Y. 


POSTAGE WILL BE PAID BY ADDRESSEE: 


International Business Machines Corporation 
Department 824 

1133 Westchester Avenue 

White Plains, New York 10604 


Fold and tape Please Do Not Staple 


Fold and tape 


NO POSTAGE 
NECESSARY 
IF MAILED 


IN THE 
UNITED STATES 


Fold and tape 


aur Buoly plos 10 nQ-— — —— 


OSEL9-0ZED ‘“W'S'N U! palug suORUeAUOD BulWWesBOIg apIND Burwwesboig TdV 


G320-6735-0 


HAND 


